/* File Name : IEventSource.java */

package com.chenwenxuan.sync.event;

/**
 * Represents the implementation requirements for any class that will generate events.
 * 
 * @author Jose Heitor
 * @version 1.0
 */
public interface IEventSource
{
  /**
   * This method is called from objects that whish to be notified of a particular event.
   * 
   * @param target The reference to the <i>listener</i> object that wants to be notifiied of the event.
   * @param event The name of the event that the <i>listener</i> object wishes to be notified of.
   */
  public void addEventHandler(IEventHandler target, String event);
  
  /**
   * This method is called from objects that no longer whish to be notified of a particular event.
   * 
   * @param target The reference to the <i>listener</i> object that no longer wants to be notifiied of the event.
   * @param event The name of event that the <i>listener</i> object no longer wishes to be notified of.
   */
  public void removeEventHandler(IEventHandler target, String event);
  
  /**
   * This method is typically called from objects that receive notification of events.
   * 
   * It provides a simple, skeletal mechanism for the <i>listener</i> object(s) receiving notification
   * of events to establish the <i>source</i> of the event.
   * 
   * @return Returns a <code>String</code> object with the <i>unique identifier</i> of the
   * source object of the event. (No pre-defined naming conventions are enforced. The developer is
   * free to implement any logic that will provide effective, <b>unique</b> identification of the objects
   * that generate events.)
   */
  public String getId();
}